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1.0 INTRODUCTION — 


In many Situations of assembling, debugging, and modifying programs, a cross- 





reference listing is an invaluabie aid. This listing is particularly useful 


when a programmer wishes to make changes in a Large program or one he does not 
know well. | 


A cross-reference is an alphabetical listing of all user-defined symbols with the 
line numbers at which the symbol was defined and used. Thus, the various places 
that a tagged location or an equated symbol is used are easily identified. 

CREF12 provides this facility to the praL-Ms*+ user. 


It should be noted that the usefulness of a CREF (CRoss-REFerence) is almost 
directly proportional to the quality of the coding. In particular, the follow- 


ing principles should be used in new coding in order to make the best use of 
Se ad 


1. Use symbolic references for beta registers, auto-index registers, 


page zero constants and temporaries, and fixed core locations. 





2. Avoid use of large displacements from a tag (e.g., TAD X+12 or 





JMP Y-6) because references to X and Y, respectively, rather than 


the locations actually used, will appear in the CREF. 





2.0 ENVIRONMENT 


CREFL2 (including its header) occupies seven blocks in the DIAL file area of any 
: unit. It is loaded into locations @ through 2777 of field 1 and is entered at 
, | 208 1n field l. 


3.0 USING CREF12 


CREFL2 is intended for use in conjunction with the LISTAPE pseudo-op of the 

DIAL-MS Assembler.. LISTAPE (with a positive argument) produces a normal 

assembler listing on a mass-storage device, rather than on the console Teletype '®) 

or line printer. The resulting data may then be processed by CREF12 to produce 
a full cross-reference of user-defined symbols and, optionally, the assembly 

listing. | 





To use CREF12, insert a LISTAPE n pseudo-op in the program of interest, where 


n is an expression whose value is between @ and 45, octal, and is taken as the 


Rteletype is a registered trademark of Teletype Corporation. 


+ LAP6-DIAL-MS is commonly referred to as DIAL-MS. 











unit number of a scratch tape (9-7) or disk (19-45) on which: the Assembler list- 
ing will be produced. The user must exercise caution in assigning units For 
LISTAPE because the listing information is written directly on the unit starting 
at block zero without regard to anything else that may be on the same unit. 
‘Therefore, unit n should be either a scratch tape or a logical disk devoted to 


scratch work. 


Typing ret irn. ae any time (after answering the "LISTING [Y OR N]?!' question 
causes CREF12 or ‘return to DIAL-MS. 


3.1 Operating Procedures 


1. Set all six sense switches on. Be sure the tape or disk unit 
assigned by the LISTAPE pseudo-op is ready and WRITE ENABLEd. 


2. Assemble the program with the LIST Command (refer to the LAP6-DIAL 
Programmer's Reference Manual, DEC~12-SE2D-D). 


3. Ifa printer is to be used for the CREF, it should be ready at 
this time. When the Editor display returns, load CREF12 by 
typing *LO CREF12,9@,) | | 


4. The following message is printed: 
UNIT #? 
Type an octal number between @ and 45, followed by carriage return, 


for the unit on which the peeling, was written. 


5. The next message is 
LISTING [Y OR N]? 


Type Y if the full assembly listing and CREF are desired; N if only 
the CREF is needed. 


Assuming the specified unit is available and ready, CREF12 will then read the 


listing (printing it if requested) and print the eross~reference. table: 
Output will be on a line printer if one is available and ready. 


Otherwise, it will be on the console teletype. 


3.2 Error Conditions 


Under some conditions, CREF12 will not be able to produce the cross-reference 


desired. 


1. iaIf there were errors in the assembly, CREF12 may interpret the 
program incorrectly, or may even be unable to process it at 
all. In the latter event, it will print "BAD INPUT" and return 
to DIAL-MS. | | 


Ze. VLE there i2s'a large number of symbols and yueevonced, the cross- 
reference table may overflow. In this case, CREF12 prints: 


SYMBOL TABLE OVERFLOW AT LINE XXxXX | 
































where XXXX is the Last line number processed. CREFL2 then 

pr. nts the cross-reference up to that line, and returns to 
DIAL-MS. This problem will arise if (NSYM*5 + NREF) is greater 
than 4894, where NSYM is the number of user-defined symbols in 
the program, and NREF is the number of references to user-defined 
symbols. If there are more than 8.856 symbols, this message 

will occur during the first pass, with XXXX equal to @P@g. 
CREF12 will print "BAD INPUT" and return to DIAL-MS. 


3) If the unit specified by the user is invalid, the DIAL-MS 


I/O routines will display NO. The user may type return to get back to DIAL. 


If a program containing a LISTAPE pseudo-op is to be assembled without getting a 
CREF, use the normal assembly procedure with the sense switches off; this 
disables the LISTAPE function. 


4.0 INTERNAL DESCRIPTION 


fitter reading the DIAL-MS I/O routines into 7TBSA~7777 ef field 1, CREF!2 requests 
two parameters from-the user: the unit fron which to read the listing, 

and whether the listing is to be printed; CREFI12 then begins its first 

pass over the data. The routine MAIN rewinds the input, initializes counters, 
and cal'’s the subroutines GETLIN and ENDLST to get a line of input and 

check it for the separator between the listing proper and 

the symbol table, respectively. nis separator 1s a line with one of two 
messages, "NO ERRORS" or "XXXX ERRORS". If the input runs out (indicated by a 
word of zero) before the separator is found, the input is invalid and processing 
is terminated with the message "BAD INPUT". If the separator is found, SYMBUILD 
takes over and reads the symbol table. Each symbol is stored in stripped ASCII 
form in field 9, followed by two words of zero. | 


When the end of data is found, control passes to PART2, which rewinds the input 
file. MAJOR calls GETLIN and ENDLST to get successive lines from the file and 
test for the end of the listing proper. After checking for the separator, MAJOR 
flows into SCAN, which collects a symbol at NAME, calls NSERCH to search the 
symbol table for it, and (if it finds the symbol) stores the line number with 
the symbol in field @. Control returns to SCAN until either carriage return, 
Slash, or "TEXT" is found. Control then returns to MAJOR to get a new 

line. 


When a separator is found, control transfers to DUMP, which prints a header, then 
reads each symbol from the file. . Each symbol and its value are printed, followed 
by the line number at which the symbol was defined, and then the line numbers 


at which the references to it were made. 


Output is terminated, and control returns to DIAL-MS, when the end of the symbol 


table is found. 








The functions of minor routines are as follows: 


BOPUP 


CRLF. 


GETBLK 


GETC 
GETLIN 
IMOVE 


IPUSH 


ISNUM 


I ZERO 


LIMIT 


NSERCH 
POCTAL 
PUTC 


TTY 


RETCHU 


Maintains SYSCOUNT to keep track of field @ utilization and 
issue the message "SYMBOL TABLE OVERFLOW AT LINE XXXX" when | 
the symbol table overflows. Called by SCAN when a reference is_ 
to be added to the symbol Lr 


Go to a new line on the Teletype or line printer. 


Get. 8 blocks from the input file. Used by GETLIN when the nour 
buffer is empty, and by MAIN and PART2 to rewind the input and 
read the first buffer load. 


Obtain the next character from the current line and return it in 
CHAR and the AC. Used by many routines. 


Get a line (a string of characters terminated by zero or line 
feed) from the input file. If LISTSW is non-zero, print it. 


Move a block of data across field boundaries. Used by SYMBUILD 
to move a new entry into the symbol table. 


Move a portion of the symbol table down. During SYMBUILD, the 
symbol table is built by pushing previous entries down to lower 
core addresses and entering each new symbol at the end of the 


list (at the top of field @). During SCAN, references to each 


symbol are stored following the symbol. [PUSH is called to make 


room for each entry. 


Examine the first four characters of he current line. If not 
octal digits, return to P+l. Otherwise, convert them to binary, 
store. binary at LINENO, and return to P+2. reyes only. by MAJOR. 


So the symbol table, starting at the (ocacien addressed by 


TEMP, for a word of zero. If none is found, return to P+l. 
Otherwise, return to P+2 with TEMP pointing to the zero. 


Calied by NSERCH to look for the next symbol and by SCAN to Find 
the end of the references to the current symbol. 


compare the value in the AC to two limits. TE the AC is zero, 
return to address in P+3; if AC is out of limits, return to 
address. in P+4. If AC is within the limits, return to P+5. Used 
by Rony routines. 


Find the symbol table entry which matches the symbol at NAME. 
Return to P+l if no match is found, or to P+2 if successful. 
Called only by SCAN. 


Print the value. in ene AC, converted to octal characters. Used 
by BOPUP to print the ine number at which overflow occurs and 
by DUMP to print the cross-reference line numbers. 


Print one character On the output device. 


Print a character string. 


Check. che keyboard flag and return to DIAL 
if return has been struck. Otherwise just 
Clear AC. | | 


























HOW TO OBTAIN SOFTWARE INFORMATION 


Announcements for new and revised software, as well as programming notes, software problems, and documenta- 
tion corrections are published by Software Information Service in the following newsletters. 


Digital Software News for the PDP-8 Family 
Digital Software News for the PDP-9/15 Family 
PDP-6/PDP-10 Software Bulletin 


These newsletters contain information applicable to software available from Digital’s Program Library. 
Please complete the card below to place your name on the newsletter mailing list. 


Questions or problems concerning DEC Software should be reported to the Software Specialist at your nearest DEC 
isevonal or district sales office. In cases where no Software Specialist is available, please send a Software Trouble 
Report form with details of the problem to: 


Software Infarmation Service 
Digital Equipment Corperation 
146 Main Street, Bldg. 3-5 
Maynard, Massachusetts 01754 


Ttoose forms, which are available without charge from the Program Library, should be fully filled out and accompa- 
nied by teletype output as well as listings or tapes of the user program to facilitate a complete investigation. An 
answer will be sent to the individual and appropriate topics of general interest will be printed in the newsletter. 


New and revised software and manuals, Software Trouble Report forms, and cumulative Software Manual Updates 
are available from the Program Library. When ordering, include the document number and a brief description of 
the programa or manual requested. Revisions of programs and documents will be announced in the newsletters and 
aprice list will be included twice yearly. Direct all inquiries and requests to: 





Program Library 

Digital hquipment Corporation 
146 Main Street, Bldg. 3-5 
Maynard, Massachusetts 01754 


Digital Lquipment Computer Users Society (DECUS) maintains a user Library and publishes a catalog of programs 
as well as the DECUSCOPE magazine for its members and non-members who request it. For further information 
please write to: 


DECUS 

Digital Equipment Corporation 
146 Main Street 

Maynard, Massachusetts 01754 
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Send Digital’s software newsletters to: 


Name 
Company Name 





Address 
Lo (zip code) 
My computer is a PDP-8/1 O PDP-8/L 2 
LINC-8 © PDP-12 © 
Pbpr-9 Q PDP-15 © Please specif 
Ppp-l0 O OTHER“. 


My system serial number is (if known) 
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CREF12 


READER’S COMMENTS 
DEC~-12-FRZB-D 


Digital Equipment Corporation maintains a continuous effort to improve the quality and usefulness of its 
publications. To do this effectively we need user feedback — your critical evaluation of this manual. 


Please comment on this manual’s completeness, accuracy, organization, usability, and readability. 


Pe ndanaitl detested c cseabeananen inatbalech aieiabictieiienstaniiseannel 
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Did you find errors in this manual? 
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12.9 cage EE IT NRE 


How can this manual be improved? 








DEC also strives to keep its customers informed of current DEC software and publications. Thus, the following period- 
ically distributed publications are available upon request. Please check the appropriate boxes for a current issue of the 
publication(s) desired. 


(.) Software Manual Update, a quarterly collection of revisions to current software manuals. 
[} User’s Bookshelf, a bibliography of current software manuals. 


1 Program Library Price List, a list of currently available software programs and manuals. 


Please describe your position. 
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